/*
 * Copyright 2017 - 2025 the original author or authors.
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program. If not, see [https://www.gnu.org/licenses/]
 */

package infra.util.xml;

import org.jspecify.annotations.Nullable;
import org.xml.sax.ContentHandler;
import org.xml.sax.XMLReader;

import java.io.InputStream;
import java.util.List;
import java.util.function.Supplier;

import javax.xml.stream.XMLEventFactory;
import javax.xml.stream.XMLEventReader;
import javax.xml.stream.XMLEventWriter;
import javax.xml.stream.XMLInputFactory;
import javax.xml.stream.XMLResolver;
import javax.xml.stream.XMLStreamException;
import javax.xml.stream.XMLStreamReader;
import javax.xml.stream.XMLStreamWriter;
import javax.xml.stream.events.XMLEvent;
import javax.xml.transform.Result;
import javax.xml.transform.Source;
import javax.xml.transform.stax.StAXResult;
import javax.xml.transform.stax.StAXSource;

/**
 * Convenience methods for working with the StAX API. Partly historic due to JAXP 1.3
 * compatibility; as of Infra 4.0, relying on JAXP 1.4 as included in JDK 1.6 and higher.
 *
 * <p>In particular, methods for using StAX ({@code javax.xml.stream}) in combination with
 * the TrAX API ({@code javax.xml.transform}), and converting StAX readers/writers into SAX
 * readers/handlers and vice-versa.
 *
 * @author Arjen Poutsma
 * @author Juergen Hoeller
 * @author <a href="https://github.com/TAKETODAY">Harry Yang</a>
 * @since 4.0
 */
public abstract class StaxUtils {

  private static final XMLResolver NO_OP_XML_RESOLVER =
          (publicID, systemID, base, ns) -> InputStream.nullInputStream();

  /**
   * Create an {@link XMLInputFactory} with Framework's defensive setup,
   * i.e. no support for the resolution of DTDs and external entities.
   *
   * @return a new defensively initialized input factory instance to use
   */
  public static XMLInputFactory createDefensiveInputFactory() {
    return createDefensiveInputFactory(XMLInputFactory::newInstance);
  }

  /**
   * Variant of {@link #createDefensiveInputFactory()} with a custom instance.
   *
   * @param instanceSupplier supplier for the input factory instance
   * @return a new defensively initialized input factory instance to use
   */
  public static <T extends XMLInputFactory> T createDefensiveInputFactory(Supplier<T> instanceSupplier) {
    T inputFactory = instanceSupplier.get();
    inputFactory.setProperty(XMLInputFactory.SUPPORT_DTD, false);
    inputFactory.setProperty(XMLInputFactory.IS_SUPPORTING_EXTERNAL_ENTITIES, false);
    inputFactory.setXMLResolver(NO_OP_XML_RESOLVER);
    return inputFactory;
  }

  /**
   * Create a JAXP 1.4 {@link StAXSource} for the given {@link XMLStreamReader}.
   *
   * @param streamReader the StAX stream reader
   * @return a source wrapping the {@code streamReader}
   */
  public static Source createStaxSource(XMLStreamReader streamReader) {
    return new StAXSource(streamReader);
  }

  /**
   * Create a JAXP 1.4 {@link StAXSource} for the given {@link XMLEventReader}.
   *
   * @param eventReader the StAX event reader
   * @return a source wrapping the {@code eventReader}
   */
  public static Source createStaxSource(XMLEventReader eventReader) throws XMLStreamException {
    return new StAXSource(eventReader);
  }

  /**
   * Create a custom, non-JAXP 1.4 StAX {@link Source} for the given {@link XMLStreamReader}.
   *
   * @param streamReader the StAX stream reader
   * @return a source wrapping the {@code streamReader}
   */
  public static Source createCustomStaxSource(XMLStreamReader streamReader) {
    return new StaxSource(streamReader);
  }

  /**
   * Create a custom, non-JAXP 1.4 StAX {@link Source} for the given {@link XMLEventReader}.
   *
   * @param eventReader the StAX event reader
   * @return a source wrapping the {@code eventReader}
   */
  public static Source createCustomStaxSource(XMLEventReader eventReader) {
    return new StaxSource(eventReader);
  }

  /**
   * Indicate whether the given {@link Source} is a JAXP 1.4 StAX Source or
   * custom StAX Source.
   *
   * @return {@code true} if {@code source} is a JAXP 1.4 {@link StAXSource} or
   * custom StAX Source; {@code false} otherwise
   */
  public static boolean isStaxSource(Source source) {
    return source instanceof StAXSource || source instanceof StaxSource;
  }

  /**
   * Return the {@link XMLStreamReader} for the given StAX Source.
   *
   * @param source a JAXP 1.4 {@link StAXSource}
   * @return the {@link XMLStreamReader}
   * @throws IllegalArgumentException if {@code source} isn't a JAXP 1.4 {@link StAXSource}
   * or custom StAX Source
   */
  @Nullable
  public static XMLStreamReader getXMLStreamReader(Source source) {
    if (source instanceof StAXSource) {
      return ((StAXSource) source).getXMLStreamReader();
    }
    else if (source instanceof StaxSource) {
      return ((StaxSource) source).getXMLStreamReader();
    }
    else {
      throw new IllegalArgumentException("Source '" + source + "' is neither StaxSource nor StAXSource");
    }
  }

  /**
   * Return the {@link XMLEventReader} for the given StAX Source.
   *
   * @param source a JAXP 1.4 {@link StAXSource}
   * @return the {@link XMLEventReader}
   * @throws IllegalArgumentException if {@code source} isn't a JAXP 1.4 {@link StAXSource}
   * or custom StAX Source
   */
  @Nullable
  public static XMLEventReader getXMLEventReader(Source source) {
    if (source instanceof StAXSource) {
      return ((StAXSource) source).getXMLEventReader();
    }
    else if (source instanceof StaxSource) {
      return ((StaxSource) source).getXMLEventReader();
    }
    else {
      throw new IllegalArgumentException("Source '" + source + "' is neither StaxSource nor StAXSource");
    }
  }

  /**
   * Create a JAXP 1.4 {@link StAXResult} for the given {@link XMLStreamWriter}.
   *
   * @param streamWriter the StAX stream writer
   * @return a result wrapping the {@code streamWriter}
   */
  public static Result createStaxResult(XMLStreamWriter streamWriter) {
    return new StAXResult(streamWriter);
  }

  /**
   * Create a JAXP 1.4 {@link StAXResult} for the given {@link XMLEventWriter}.
   *
   * @param eventWriter the StAX event writer
   * @return a result wrapping {@code streamReader}
   */
  public static Result createStaxResult(XMLEventWriter eventWriter) {
    return new StAXResult(eventWriter);
  }

  /**
   * Create a custom, non-JAXP 1.4 StAX {@link Result} for the given {@link XMLStreamWriter}.
   *
   * @param streamWriter the StAX stream writer
   * @return a source wrapping the {@code streamWriter}
   */
  public static Result createCustomStaxResult(XMLStreamWriter streamWriter) {
    return new StaxResult(streamWriter);
  }

  /**
   * Create a custom, non-JAXP 1.4 StAX {@link Result} for the given {@link XMLEventWriter}.
   *
   * @param eventWriter the StAX event writer
   * @return a source wrapping the {@code eventWriter}
   */
  public static Result createCustomStaxResult(XMLEventWriter eventWriter) {
    return new StaxResult(eventWriter);
  }

  /**
   * Indicate whether the given {@link Result} is a JAXP 1.4 StAX Result or
   * custom StAX Result.
   *
   * @return {@code true} if {@code result} is a JAXP 1.4 {@link StAXResult} or
   * custom StAX Result; {@code false} otherwise
   */
  public static boolean isStaxResult(Result result) {
    return (result instanceof StAXResult || result instanceof StaxResult);
  }

  /**
   * Return the {@link XMLStreamWriter} for the given StAX Result.
   *
   * @param result a JAXP 1.4 {@link StAXResult}
   * @return the {@link XMLStreamReader}
   * @throws IllegalArgumentException if {@code source} isn't a JAXP 1.4 {@link StAXResult}
   * or custom StAX Result
   */
  @Nullable
  public static XMLStreamWriter getXMLStreamWriter(Result result) {
    if (result instanceof StAXResult) {
      return ((StAXResult) result).getXMLStreamWriter();
    }
    else if (result instanceof StaxResult) {
      return ((StaxResult) result).getXMLStreamWriter();
    }
    else {
      throw new IllegalArgumentException("Result '" + result + "' is neither StaxResult nor StAXResult");
    }
  }

  /**
   * Return the {@link XMLEventWriter} for the given StAX Result.
   *
   * @param result a JAXP 1.4 {@link StAXResult}
   * @return the {@link XMLStreamReader}
   * @throws IllegalArgumentException if {@code source} isn't a JAXP 1.4 {@link StAXResult}
   * or custom StAX Result
   */
  @Nullable
  public static XMLEventWriter getXMLEventWriter(Result result) {
    if (result instanceof StAXResult) {
      return ((StAXResult) result).getXMLEventWriter();
    }
    else if (result instanceof StaxResult) {
      return ((StaxResult) result).getXMLEventWriter();
    }
    else {
      throw new IllegalArgumentException("Result '" + result + "' is neither StaxResult nor StAXResult");
    }
  }

  /**
   * Create a {@link XMLEventReader} from the given list of {@link XMLEvent}.
   *
   * @param events the list of {@link XMLEvent XMLEvents}.
   * @return an {@code XMLEventReader} that reads from the given events
   */
  public static XMLEventReader createXMLEventReader(List<XMLEvent> events) {
    return new ListBasedXMLEventReader(events);
  }

  /**
   * Create a SAX {@link ContentHandler} that writes to the given StAX {@link XMLStreamWriter}.
   *
   * @param streamWriter the StAX stream writer
   * @return a content handler writing to the {@code streamWriter}
   */
  public static ContentHandler createContentHandler(XMLStreamWriter streamWriter) {
    return new StaxStreamHandler(streamWriter);
  }

  /**
   * Create a SAX {@link ContentHandler} that writes events to the given StAX {@link XMLEventWriter}.
   *
   * @param eventWriter the StAX event writer
   * @return a content handler writing to the {@code eventWriter}
   */
  public static ContentHandler createContentHandler(XMLEventWriter eventWriter) {
    return new StaxEventHandler(eventWriter);
  }

  /**
   * Create a SAX {@link XMLReader} that reads from the given StAX {@link XMLStreamReader}.
   *
   * @param streamReader the StAX stream reader
   * @return a XMLReader reading from the {@code streamWriter}
   */
  public static XMLReader createXMLReader(XMLStreamReader streamReader) {
    return new StaxStreamXMLReader(streamReader);
  }

  /**
   * Create a SAX {@link XMLReader} that reads from the given StAX {@link XMLEventReader}.
   *
   * @param eventReader the StAX event reader
   * @return a XMLReader reading from the {@code eventWriter}
   */
  public static XMLReader createXMLReader(XMLEventReader eventReader) {
    return new StaxEventXMLReader(eventReader);
  }

  /**
   * Return a {@link XMLStreamReader} that reads from a {@link XMLEventReader}.
   * Useful because the StAX {@code XMLInputFactory} allows one to create an
   * event reader from a stream reader, but not vice-versa.
   *
   * @return a stream reader that reads from an event reader
   */
  public static XMLStreamReader createEventStreamReader(XMLEventReader eventReader) throws XMLStreamException {
    return new XMLEventStreamReader(eventReader);
  }

  /**
   * Return a {@link XMLStreamWriter} that writes to a {@link XMLEventWriter}.
   *
   * @return a stream writer that writes to an event writer
   */
  public static XMLStreamWriter createEventStreamWriter(XMLEventWriter eventWriter) {
    return new XMLEventStreamWriter(eventWriter, XMLEventFactory.newFactory());
  }

  /**
   * Return a {@link XMLStreamWriter} that writes to a {@link XMLEventWriter}.
   *
   * @return a stream writer that writes to an event writer
   */
  public static XMLStreamWriter createEventStreamWriter(XMLEventWriter eventWriter, XMLEventFactory eventFactory) {
    return new XMLEventStreamWriter(eventWriter, eventFactory);
  }

}
